eslint-scope

ESLint Scope

ESLint Scope is the ECMAScript scope analyzer used in ESLint. It is a fork of escope.

Install

npm i eslint-scope --save

📖 Usage

To use in an ESM file:

import * as eslintScope from 'eslint-scope';

To use in a CommonJS file:

const eslintScope = require('eslint-scope');

In order to analyze scope, you'll need to have an ESTree compliant AST structure to run it on. The primary method is eslintScope.analyze(), which takes two arguments:

• ast - the ESTree-compliant AST structure to analyze.
• options (optional) - Options to adjust how the scope is analyzed, including:

• ignoreEval (default: false) - Set to true to ignore all eval() calls (which would normally create scopes).
• nodejsScope (default: false) - Set to true to create a top-level function scope needed for CommonJS evaluation.
• impliedStrict (default: false) - Set to true to evaluate the code in strict mode even outside of modules and without "use strict".
• ecmaVersion (default: 5) - The version of ECMAScript to use to evaluate the code.
• sourceType (default: "script") - The type of JavaScript file to evaluate. Change to "module" for ECMAScript module code.
• childVisitorKeys (default: null) - An object with visitor key information (like eslint-visitor-keys). Without this, eslint-scope finds child nodes to visit algorithmically. Providing this option is a performance enhancement.
• fallback (default: "iteration") - The strategy to use when childVisitorKeys is not specified. May be a function.
• jsx (default: false) - Enables the tracking of JSX components as variable references.

Example:

import * as eslintScope from 'eslint-scope';
import * as espree from 'espree';
import estraverse from 'estraverse';

const options = {
    ecmaVersion: 2022,
    sourceType: "module"
};

const ast = espree.parse(code, { range: true, ...options });
const scopeManager = eslintScope.analyze(ast, options);

const currentScope = scopeManager.acquire(ast);   // global scope

estraverse.traverse(ast, {
    enter (node, parent) {
        // do stuff

        if (/Function/.test(node.type)) {
            currentScope = scopeManager.acquire(node);  // get current function scope
        }
    },
    leave(node, parent) {
        if (/Function/.test(node.type)) {
            currentScope = currentScope.upper;  // set to parent scope
        }

        // do stuff
    }
});

API

The following section describes the API for this package. You can also read the docs.

ScopeManager

The ScopeManager class is at the core of eslint-scope and is returned when you call eslintScope.analyze(). It manages all scopes in a given AST.

Properties

• scopes - An array of all scopes.
• globalScope - Reference to the global scope.

Methods

• acquire(node, inner) Acquires the appropriate scope for a given node.

  • node - The AST node to acquire the scope from.
  • inner - Optional boolean. When true, returns the innermost scope, otherwise returns the outermost scope. Default is false.
  • Returns: The acquired scope or null if no scope is found.

• acquireAll(node) Acquires all scopes for a given node.

  • node - The AST node to acquire scopes from.
  • Returns: An array of scopes or undefined if none are found.

• release(node, inner) Returns the upper scope for a given node.

  • node - The AST node to release.
  • inner - Optional boolean. When true, returns the innermost upper scope, otherwise returns the outermost upper scope. Default is false.
  • Returns: The upper scope or null if no upper scope exists.

• getDeclaredVariables(node) Get variables that are declared by the node.

  • node - The AST node to get declarations from.
  • Returns: An array of variable objects declared by the node. If the node doesn't declare any variables, it returns an empty array.

• isGlobalReturn() Determines if the global return statement should be allowed.

  • Returns: true if the global return is enabled.

• isModule() Checks if the code should be handled as an ECMAScript module.

  • Returns: true if the sourceType is "module".

• isImpliedStrict() Checks if implied strict mode is enabled.

  • Returns: true if implied strict mode is enabled.

• isStrictModeSupported() Checks if strict mode is supported based on ECMAScript version.

  • Returns: true if the ECMAScript version supports strict mode.

Scope Objects

Scopes returned by the ScopeManager methods have the following properties:

• type - The type of scope (e.g., "function", "block", "global").
• variables - Array of variables declared in this scope.
• set - A Map of variable names to Variable objects for variables declared in this scope.
• references - Array of references in this scope.
• through - Array of references in this scope and its child scopes that aren't resolved in this scope or its child scopes.
• variableScope - Reference to the closest variable scope.
• upper - Reference to the parent scope.
• childScopes - Array of child scopes.
• block - The AST node that created this scope.

GlobalScope

The GlobalScope class is a specialized scope representing the global execution context. It extends the base Scope class with additional functionality for handling implicitly defined global variables.

Properties

• implicit - Tracks implicitly defined global variables (those used without declaration).
  • set - A Map of variable names to Variable objects for implicitly defined globals.
  • variables - Array of implicit global Variable objects.
  • left - Array of References that need to be linked to the variable they refer to.

Variable Objects

Each variable object has the following properties:

• name - The variable name.
• identifiers - Array of identifier nodes declaring this variable.
• references - Array of references to this variable.
• defs - Array of definition objects for this variable.
• scope - The scope object where this variable is defined.

Contributing

Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the ESLint Contributor Guidelines, so please be sure to read them before contributing. If you're not sure where to dig in, check out the issues.

Security Policy

We work hard to ensure that ESLint Scope is safe for everyone and that security issues are addressed quickly and responsibly. Read the full security policy.

Build Commands

• npm test - run all linting and tests
• npm run lint - run all linting

License

ESLint Scope is licensed under a permissive BSD 2-clause license.

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

Diamond Sponsors

Platinum Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors

Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.

Similar packages

Other packages similar to eslint-scope

escope

Escope is another scope analysis tool for JavaScript. It is similar to eslint-scope but is no longer actively maintained. Escope was the predecessor to eslint-scope and served a similar purpose in analyzing variable scope within JavaScript code.

jscodeshift

Jscodeshift is a toolkit for running codemods over multiple JavaScript or TypeScript files. It uses a different approach but can be used for similar scope analysis and transformation tasks. Jscodeshift provides a more extensive API for manipulating the AST and is often used for large-scale codebase refactors.

babel-traverse

Babel-traverse allows you to traverse and manipulate the AST generated by Babel. While its primary use is for Babel plugins and transformations, it can also be used to analyze scope and variable declarations in a manner similar to eslint-scope. Babel-traverse is part of the larger Babel ecosystem, which is widely used for JavaScript compilation and transformation.